On a runner with no route to TEST-NET-1 (192.0.2.0/24) connect() fails
fast with ENETUNREACH instead of dropping the SYN, so the timeout path
can't be exercised. Skip (Assume) in that case rather than asserting a
timeout, while still proving the call never blocked on the OS connect
timeout.

GitHub now forces actions onto Node 24 (glibc >= 2.27), which cannot run
inside the manylinux2014 (glibc 2.17) container the linux-x86-64 native
build used; actions/checkout failed before compilation. The old
Node-20-glibc-217 override only patched /__e/node20, not /__e/node24.

Switch the job to quay.io/pypa/manylinux_2_28_x86_64 (glibc 2.28, runs
stock Node 24) and drop the Node hack, nasm src.rpm rebuild, and manual
CMake download, mirroring the linux-aarch64 job that already builds on
manylinux_2_28.

The pooled QuestDB facade built its ingest Senders from config strings
only (SenderPool -> Sender.fromConfig), so the programmatic ingest
callbacks -- SenderErrorHandler and SenderConnectionListener -- were
unreachable: a facade user got the default loud-not-silent handlers with
no way to observe async ingest errors or connection transitions.

Expose both as QuestDBBuilder setters and thread them to every pooled
Sender:
- QuestDBBuilder.errorHandler(...) / .connectionListener(...)
- QuestDBImpl gains a full constructor carrying the callbacks; the public
  constructor forwards them and the 12-arg white-box test-seam constructor
  is preserved as a delegating shim (null callbacks).
- SenderPool gains a full constructor + applyUserCallbacks() that applies
  the callbacks to every sender it builds (both the non-SF and SF paths);
  the 8-arg test-seam constructor is preserved as a shim.

Recovery delegates (internal, short-lived, OFF-mode drain senders) are
deliberately excluded so the user's callbacks never see events from
internal machinery.

Defaults are null -> behaviour is unchanged unless a callback is set.

Tests: QuestDBFacadeCallbacksTest prewarms one ingest sender at a dead
port in async mode with a tight reconnect budget and asserts the
facade-wired errorHandler receives the budget-exhaustion SenderError and
the facade-wired connectionListener observes connection events -- no
server required.

Remove the committed darwin-aarch64/darwin-x86-64 libquestdb.dylib and build
them on the macOS runners, matching the Linux/Windows approach. No native
binaries remain committed; all are compiled during the test CI.

- build_native.yaml: add a macOS build step (brew cmake/nasm,
  MACOSX_DEPLOYMENT_TARGET=13.0), detect darwin-aarch64 vs darwin-x86-64 via
  uname -m, and copy the dylib into src/main/resources/.../bin/<platform>/.
- Init the zstd submodule on all platforms (it was skipped on Darwin).

Release artifacts are still produced by the release GitHub Action.

The macos-15 (x64) agent hardware no longer exists, so remove the mac-x64
matrix entry. macOS is now tested on mac-aarch64 only. The darwin-x86-64
.dylib is still produced by the release GitHub Action, and build_native.yaml
keeps its uname-based arch detection so an x64 macOS runner would still build
correctly if ever reintroduced.

The GitHub Actions build-jdk8 job ran the full test suite against the
committed native libraries, which are now removed. Without the .so the
io.questdb.client.std.{Os,Files,Unsafe,...} static initializers fail with
NoClassDefFound (1289 errors).

Compile the native .so from source first (zstd submodule + cmake/nasm/
build-essential), against the JDK 8 JNI headers, and copy it into
src/main/resources/.../bin/linux-x86-64 so it survives 'mvn clean' and loads
via the production bin/<platform> path. Update the now-stale comment.

glibc 2.17 moved clock_gettime() into libc under a new GLIBC_2.17 version
node. Building the release .so in a modern container (manylinux_2_28) binds
clock_gettime@GLIBC_2.17, which raises the whole library's glibc floor to 2.17
and breaks loading on glibc 2.14-2.16 hosts.

Add src/main/c/share/glibc_compat.h with a .symver directive forcing the
reference back to clock_gettime@GLIBC_2.2.5 (x86-64 glibc only; no-op on
aarch64/macOS/Windows), include it from net.c and os.c, list it in the
CMake sources, and document the glibc floor in rebuild_native_libs.yml.

… notes

The Coverage Report job runs 'mvn -P jacoco test' on core but had no native
build step, so after dropping the committed binaries it failed to load
libquestdb.so (NoClassDefFound in io.questdb.client.std.*). Add the
build_native.yaml template before the coverage test run, matching the
BuildAndTest job. The job runs on Linux, so it compiles libquestdb.so.

Collapse the dual ingest/query config surface on the QuestDB facade into a
single configuration string for the whole cluster. A QuestDB cluster is one
logical target reached over QWP for both ingest and query, so one ws/wss
string -- listing every node in a single `addr` server list -- now drives
both the sender and query pools.

- QuestDBBuilder: drop ingestConfig()/queryConfig(); fromConfig() sets the
  one cluster config. Remove the cross-side pool-key conflict resolution
  (no two strings to reconcile) -- resolvePoolInt/Long read one ConfigView.
  build() validates the single string with both the ingest and egress
  validators; each side applies the keys it owns and ignores the rest.
- QuestDB: remove the connect(ingest, query) overload; connect(config) and
  builder() now document the one-config/server-list model.
- QuestDBImpl is unchanged: the builder passes the one config to both pool
  slots, preserving the white-box reflection seam.

Tests: TestWebSocketServer now serves both pools from one config like a real
node -- SERVER_INFO is emitted only on the egress /read path (the ingest
/write ACK stream would choke on it), plus a setRejectReadUpgrade() toggle to
fail just the query upgrade. Rewrote QuestDBBuilderTest and updated the
facade callback/recovery/write-only tests and the examples accordingly.

…n-string key

Make writeOnly() deliver its own promise and reach it from the connect string.

Previously "start even when the server is down" needed two knobs that look
unrelated: writeOnly() (skip the fail-fast read pool) plus
initial_connect_retry=async (keep the write prewarm from fail-fast-ing). The
former governs the read side, the latter the write side, so writeOnly() alone
still hard-failed build() when sender_pool_min >= 1 and the server was down.

- writeOnly() now defaults the ingest side to a non-blocking async initial
  connect (injected right after the schema so an explicit initial_connect_retry
  in the user's string still wins, last-write-wins). build() returns promptly
  with the server down and the sender pool warm; writes buffer until the wire
  comes up.
- New POOL-side connect-string key write_only=on, equivalent to .writeOnly(),
  so the mode is reachable from any config string (and QuestDB.connect). The
  two ws clients ignore it; the facade routes on it.

Tests: writeOnly() with sender_pool_min defaulting to 1 and no
initial_connect_retry now builds without fail-fast; write_only=on routes to
the ingest-only path via builder and via connect(). PoolConfigHonoredTest's
drift guard skips the routing flag (not a numeric sizing knob).

…nabled

Strengthen the server-recovery test to assert what the write-only mode is NOT:
on a normal facade built while the server is down (lazy read pool via
query_pool_min=0, async ingest), query() must still hand back a usable builder
*before* the server is up -- reads are enabled, just deferred -- and the
deferred reader connects on the first submit once the server comes up. This is
the read-capable counterpart to write-only, where query() throws for the life
of the handle.

…ant startup)

Drop write-only mode (it permanently disabled reads -- query()/newQuery()
threw for the life of the handle) in favour of a read-capable tolerant-startup
flag, lazy_connect, reachable from the connect string.

lazy_connect=true:
- a) starts even when the server is down -- the ingest side connects async and
     the read pool defaults to query_pool_min=0, so neither side fail-fasts;
- b) buffers writes while the server is down (async sender);
- c) reads once the server is up -- the read pool stays ENABLED and connects
     lazily on the first query.

Because both sides must start non-blocking, a knob that forces a blocking /
fail-fast startup is a configuration conflict, rejected up front with a clear
remedy:
- initial_connect_retry other than async (off/false/on/true/sync), and
- an explicit query_pool_min > 0 (connect string or builder call).

Changes:
- ConfigSchema: write_only -> lazy_connect (Side.POOL; both clients ignore it).
- ConfigView.getBool: accept true/false (and on/off).
- QuestDBBuilder: remove writeOnly()/buildWriteOnly(); build() resolves
  lazy_connect, validates the two conflicts, defaults query_pool_min to 0 and
  injects initial_connect_retry=async when unset.
- QuestDBImpl: remove the write-only constructor/flag and requireQueryEnabled;
  the query pool is always built (the white-box reflection seam is unchanged).
- Tests: QuestDBWriteOnlyTest -> QuestDBLazyConnectTest (start+write while down,
  reads stay enabled, both conflicts via string and builder, true/on parsing);
  QuestDBServerRecoveryTest now dogfoods lazy_connect=true for the full
  down->write->up->read lifecycle; PoolConfigHonoredTest drift guard skips the
  flag.

…e timeout

QwpQueryClient.runUpgradeWithTimeout wrapped connect() and upgrade() in one
try block, so a connect_timeout overage -- the timeout-flagged
HttpClientException from doConnect()'s CONNECT_TIMEOUT path -- was caught by
the isTimeout() branch meant for upgrade() and rewritten as
"WebSocket upgrade to host:port exceeded auth_timeout=<authTimeoutMs>ms".
A user with connect_timeout=500 and auth_timeout_ms=15000 saw, after ~500ms,
an error blaming a 15000ms auth timeout (wrong phase and wrong value).

Move connect() outside the upgrade try so the auth_timeout rewrite only
applies to genuine upgrade-phase timeouts; connect-phase failures propagate
with their own "connect timed out ..." message. The failover walk is
unchanged (the exception is still a transport error and the next endpoint is
tried). The ingest side (QwpWebSocketSender) was already correct -- it routes
through QwpUpgradeFailures.classify, which leaves the connect-timeout
exception unmodified.

Add QwpQueryClientConnectTimeoutTest: a TEST-NET-1 blackhole connect with
connect_timeout < auth_timeout must report connect_timeout, not auth_timeout.
It skips gracefully when the runner has no route to the blackhole, mirroring
NetConnectTimeoutTest. Verified it fails on the pre-fix code with the exact
misreported message.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…nly removal

The PoolHousekeeper reap loop wrapped queryPool.reapIdle() in an
`if (queryPool != null)` guard whose comment ("null for a write-only
handle") described write-only mode. That mode was removed in the
lazy_connect change (7491d95): QuestDBImpl now builds the query pool
unconditionally and is the sole PoolHousekeeper caller, so the field is
never null in a live handle. The null branch is unreachable and the
comment is stale -- drop both. The outer best-effort Throwable catch
stays; it has nothing to do with write-only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ConfigView.getBool accepts true/false and on/off, but its invalid-value
error read "(expected true, false)", under-reporting the accepted forms
(e.g. lazy_connect=on is valid yet the message implies otherwise). List
all four, matching getBoolOnOff's convention of naming exactly what it
accepts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Reshape the QuestDB facade so reads and writes share one pooled-lease
model, and remove the thread-affine footguns on both sides.

Ingest:
- Remove QuestDB.sender() and releaseSender(), along with the entire
  thread-pin subsystem behind them (SenderPool.pinToCurrentThread,
  releaseCurrentThread, clearPinIfCurrent, the threadAffine ThreadLocal,
  and the PooledSender invalidated flag that existed only to make pinning
  safe). borrowSender() is now the only way to lease a Sender.

Egress:
- Add QuestDB.borrowQuery(), a closeable, non-allocating Query lease that
  mirrors borrowSender(). Each pooled QueryWorker owns one pre-allocated
  QueryImpl, handed out reset on borrow; submit() dispatches on the held
  worker (single-flight) and close() returns it to the pool. The worker
  no longer auto-releases per query.
- Remove query(), newQuery(), and executeSql(). Reads now connect at
  borrow time rather than submit time; under lazy_connect the read pool
  still defaults to min=0, so build() does not fail-fast while the server
  is down.

Test seams:
- Make the white-box seam constructors public and annotate @testonly
  where production never calls them (QuestDBImpl, SenderPool). The
  QueryClientPool connectHook ctor stays public without @testonly because
  QuestDBImpl constructs the query pool through it. Tests now call these
  constructors directly instead of via reflection.

Update the client tests, the usage example, and the startup/failover
design doc to the new API.

try (server) on an effectively-final existing variable is Java 9+ syntax
(JEP 213) and fails the JDK 8 test-compile (the source-of-truth target)
with -source 1.8, breaking the build-jdk8 CI job and the release build
before any test runs. Inline the resource construction into the
try-with-resources declaration, which is valid on Java 8 and keeps the
server variable name used throughout the body.

…se-after-close

A pooled Query/Sender handle was the reused per-slot object itself, guarded
only by a non-volatile in-use/borrowed flag. Once a worker/slot was released
and re-borrowed, that flag flips back to "live", so a stale handle's
close()/cancel()/write would leak into a *different* borrow: a duplicate close
double-released the worker/slot (enqueued twice -> two concurrent borrowers on
one non-thread-safe client/delegate), and a cached Completion.cancel() or stale
write hit whatever borrow now owns it. Idempotent close() and no-op cancel()
are documented contracts, so this was reachable from contract-legal code, not
just misuse, with pool-wide blast radius and no -ea guard.

Fix: give every borrow its own immutable generation, stamped under the pool
lock when the worker/slot is handed out and bumped again when it is returned.
The reused state stays on the slot; callers get a thin per-borrow handle that
carries the generation and validates it on every operation:
  - close()/cancel() are no-ops on a stale generation (idempotency preserved),
  - submit()/data writes throw,
  - release/giveBack/discardBroken re-check the generation under the pool lock
    so a worker/slot can never be enqueued twice, plus an -ea assert that it is
    not already in the available deque.

Egress: QueryImpl stops being the user-facing Query; new QueryLease wraps it.
Ingest: new SenderSlot is the reused slot; PooledSender becomes the per-borrow
wrapper (keeps the public name, so borrow() still returns it). The per-submit
path stays allocation-free; only the small lease handle is created per borrow
(routinely scalar-replaced under try-with-resources).

Adds QueryLeaseGenerationTest and SenderLeaseGenerationTest covering the
double-release and cross-borrow cancel/write paths; updates the white-box
tests to the new shapes. Full core suite green under -ea (the lone failure is
the unrelated pre-existing FilesTest M2, which fails identically on master).

QueryImpl.cancel(gen) validated the lease generation with an unlocked
volatile read and then issued the wire cancel with no lock, so the two
steps were not atomic. cancel() is a cross-thread watchdog/timeout API,
so this is a TOCTOU: a watchdog can pass the generation check, get
preempted while the lease is released (close -> release bumps the
generation) and the worker is re-borrowed and re-submitted by another
caller, then resume and call cancelInFlight() -- aborting that caller's
in-flight query with a spurious STATUS_CANCELLED. The client never
resets its cancel state on release/re-borrow, so the stale cancel lands
either via the wire requestCancel(currentRequestId) or via the surviving
pendingCancel latch the next executeOnce consumes.

Route the cancel through QueryClientPool.cancelIfCurrent(worker, gen),
which re-checks worker.generation() == gen and issues the wire cancel
together under the pool lock -- the same lock acquire()/release() bump
the generation under. Once cancelIfCurrent holds the lock the generation
cannot change, so a cancel whose lease has gone stale is dropped instead
of hitting the new borrower. The cancel itself is non-blocking (a
volatile flag plus an AtomicLong set), so the lock is held only briefly.
cancel() keeps a cheap unlocked fast-path that drops an obviously-stale
or already-done cancel without taking the lock; the authoritative check
stays under the lock. close() routes its abort-on-unawaited-close through
the same path, closing the identical window on its cancelInFlight() call.

QueryLeaseGenerationTest.testStaleCancelDoesNotReachClient only covered
the already-stale case (it pre-advanced the generation, leaving no
check->act window), so it could not catch this. Add
testConcurrentCancelDoesNotReachClientAfterReborrow: it holds the pool
lock so a concurrent cancel parks inside the re-check, advances the
generation (release + re-borrow) under the lock, then releases it and
asserts the parked cancel observed the new generation and never reached
the client. The new test fails against the unlocked check-then-cancel and
passes with the locked path.

JavaTlsClientSocket.startTlsSession ran the TLS handshake with raw
delegate.recv/delegate.send on a non-blocking socket and never waited on
socket readiness. A peer that completed the TCP connect but stalled
before its half of the handshake left the engine in NEED_UNWRAP with
recv returning 0 (would-block), so the loop re-read in a tight cycle: a
100% CPU busy-spin with no deadline. connect_timeout bounded only the TCP
connect, and the WebSocket upgrade's auth/request timeout never covered
the handshake, so a stalled wss:// (e.g. QuestDB Cloud) handshake could
pin a core indefinitely and defeat a bounded connect.

Drive the handshake through the client's existing deadline-aware ioWait,
the same primitive recvOrDie/doSend already use. When the socket would
block, the handshake hands control to a SocketReadinessWaiter that parks
on epoll/kqueue/select for the remaining connect budget and throws a
timeout-flagged exception once it is spent. This removes the spin and
bounds the handshake in one change: both NEED_UNWRAP (recv == 0) and the
NEED_WRAP send loop (send == 0) now wait instead of spinning.

doConnect now calls setupIoWait() before the handshake (so the fd is
registered when the waiter parks) and bounds the handshake by
connect_timeout, falling back to the request timeout when connect_timeout
is unset, so the handshake can no longer hang or spin even with the
default config. The connect TLS block disconnects on any handshake error
(including the waiter's timeout) so the fd and native buffers do not leak.
Both HttpClient (https) and WebSocketClient (wss) connect paths share the
fix.

Extracted the handshake loop into runHandshake(waiter) so a stub
SSLEngine can exercise the wait paths. Added two tests:
testHandshakeWaitsForReadabilityInsteadOfBusySpinning drives a stalled
peer and asserts the handshake yields to the waiter exactly once (a
method-level timeout fails the test if the spin returns), and
testHandshakeCompletesWithoutWaitingWhenEngineMakesProgress guards the
happy path.

awaitConnectComplete reset its time baseline (start = now) on every EINTR
and subtracted only whole milliseconds of elapsed time. Under a
high-frequency signal storm on the connecting thread -- e.g. a wall-clock
profiler or interval timer interrupting the blocked poll() more than once
per millisecond -- each interval truncated to 0 ms, so the budget never
decremented and poll() was re-armed with the full timeout every
iteration. The connect timeout could then extend well past its bound, or
never fire at all, contradicting the comment that EINTR storms cannot
extend it. Even at lower rates each interrupt discarded up to ~1 ms of
accounting, drifting the timeout one-directionally.

Compute one absolute monotonic deadline up front and derive the remaining
poll() budget from it each iteration. The remaining time can only
decrease, so the timeout is a strict upper bound regardless of interrupt
frequency; truncation now only under-shoots the final poll by < 1 ms,
which never extends the wait. The success, refused, and timeout paths are
otherwise unchanged.

Validated: NetConnectTimeoutTest (loopback success, refused-vs-timeout,
black-hole timeout within budget) passes against the rebuilt library. A
standalone harness driving the old vs new logic under a simulated 2.5 kHz
EINTR storm confirms the old logic runs unbounded (aborted at >10x the
budget) while the new logic returns at the budget. A deterministic
regression test at the JNI layer is not practical: Java cannot target a
POSIX signal at the specific connecting thread, and the only hanging-
connect fixture available (TEST-NET-1 black-hole) is routing-dependent
and already Assume-skipped on most runners.

Rebuilds the committed linux-x86-64 libquestdb.so from the net.c change
(mirrors the copy step in ci.yml); other platforms are refreshed by the
rebuild-native-libs workflow.

The build_native.yaml step comment claimed "macOS uses the committed
.dylib and is skipped inside the template." Both halves are now false:
this branch dropped all committed dylibs and added a macOS build step to
build_native.yaml (an active Darwin-conditioned step), so the dylib is
compiled fresh on the mac-aarch64 agent like the .so/.dll. The stale
comment could mislead a maintainer into skipping macOS in the template,
which would hard-break the mac leg since no committed dylib remains.
Reword to state that every platform's binary is built on its own native
agent and none are committed.

testBrokenSenderIsNotReturnedToPool asserted assertNotSame(first,
second) on the two PooledSender wrappers. SenderPool.borrow() allocates
a fresh PooledSender on every call, so that comparison is unconditionally
true and proves nothing: it stays green whether or not the broken slot
was discarded. With the discard logic reverted the test failed only
incidentally, when second.close() re-threw on the recycled broken
delegate, masking the real intent.

Compare the underlying SenderSlot instead via the existing slotOf()
helper, mirroring testBorrowReturnRecyclesSameDecorator. The pool
recycles slots, not wrappers, so a broken slot leaking back to the next
borrower now surfaces as the same slot and fails the assertion directly.
The finally swallows the incidental close() exception so the assertion
result is what surfaces. Verified by injecting the bug (giveBack instead
of discardBroken on flush failure): the corrected assertion fails as a
clean Failure at the assertion line, and passes with correct code.

Also document the QueryWorker lost-dispatch coverage boundary in
QueryWorkerTest: the single-flight-reuse race fix has no deterministic
unit reproduction here because it needs the worker mid-runOn(client)
when the user thread re-dispatches, which requires a live query client.
That regression is guarded end-to-end by
QuestDBFacadeE2ETest.testSustainedMixedConcurrency in the parent repo;
testShutdownRacingDispatchMustNotStrandCaller covers only the adjacent
shutdown branch.

Query.close() used to drain an in-flight submit with an unbounded,
uninterruptible wait: while (!done) doneCondition.awaitUninterruptibly().
Because the lease model makes close() mandatory (try-with-resources),
ordinary code that bounded its own await(timeout) and gave up still hit
this drain and could block the caller for the full remaining query
duration when the server was slow to honor the cancel. Worse, when a
QuestDB.close() raced an in-flight lease close() and the client I/O
thread failed to join within shutdownJoinMs, QwpQueryClient.close()
skipped closePool() -- the synthetic-terminal source -- so done was
never set and the lease close() hung forever.

Make the drain bounded and interruptible, and fail safe on timeout:

- QueryImpl.close() now waits at most closeQueryTimeoutMillis via
  awaitNanos and aborts on interrupt (re-raising the flag). A caller is
  never pinned to the full query duration.
- On timeout or interrupt the worker is discarded, not returned: its
  connection may still carry late RESULT_* frames for the abandoned
  query, which would corrupt the next borrower's stream. The pool grows
  a fresh worker on the next borrow. QueryClientPool.discard() mirrors
  the ingest side's discardBroken (closed/stale-generation guarded).
- QueryWorker.shutdown() now interrupts the dispatch thread. takeEvent()
  (QwpSpscQueue.take) is interrupt-aware and executeOnce() turns the
  InterruptedException into a terminal -> signalDone, so a caller parked
  in close() is released even when the I/O thread is wedged and
  closePool() never runs. This closes the hang-forever race and makes
  QuestDB.close() more prompt.

Add the query_close_timeout_ms pool knob (default 5000ms, symmetric with
the ingest close_flush_timeout_millis) via
QuestDBBuilder.queryCloseTimeoutMillis(long), wired through QuestDBImpl
to the pool and guarded by PoolConfigHonoredTest's drift check. Update
the Query.close() Javadoc to state the bounded/interruptible/discard
contract.

QueryCloseDrainTest covers the new behavior deterministically with a
no-op connect hook: close() returns within the budget and discards a
worker that does not drain, an interrupt aborts the drain promptly, and
an already-drained worker is returned for reuse. The dispatch-thread
interrupt's effect on a genuinely stuck execute() is verified by
construction here; its end-to-end reproduction lives in the parent
repo's concurrency tests.